/******************************************************************************
 * FILENAME     :   ring_buffer.h
 * AUTHOR       :   Ahmed Abdelrazek
 * CREATION     :   2011/03/15
 * DESCRIPTION  :   This file specifies the APIs of a ring buffer.
 * 					The buffer is made specifically and optimized for single reader and
 * 					single writer operation.
 * 					it is thread safe against simultaneous access from both the reader
 * 					and the writer. this is achieved without any LOCKS, simply by reserving
 * 					one entry to isolate reading operation completely from writing operation
 * 					by accessing either the reader index or the writer index.
 *
 * 					It does not contain anything that prevent different tasks to write
 * 					and/or read, but if different writers or readers, a lock is required
 * 					to make either write or read function atomic.
 *
 *
 *                  Copyright (c) 2007-2011 Research in Motion Limited
 *
 ******************************************************************************/

#ifndef _RING_BUFFER_H_
#define _RING_BUFFER_H_

#include <egos_types.h>

// size must be a power of 2
typedef struct
{
	uint32 	maxSize_1;
	uint32 	readIdx;
	uint32 	writeIdx;
	void** 	entries;

	// for sanity checks
	EgosTaskId 	reader;
	EgosTaskId 	writer;
} RingBuffer;

/*******************************************************************************
 * Function name: RingBufferCreate
 *
 * Arguments:	  uint32 	size
 *
 * return:		  RingBuffer*
 *
 * Description:
 *
 *******************************************************************************/
RingBuffer* RingBufferCreate(uint32 size, EgosTaskId reader, EgosTaskId writer);

/*******************************************************************************
 * Function name: RingBufferIsEmpty
 *
 * Arguments:	  RingBuffer 	*q
 *
 * return:		  BOOL
 *
 * Description:
 *
 *******************************************************************************/
bool RingBufferIsEmpty(RingBuffer *q);

/*******************************************************************************
 * Function name: RingBufferIsFull
 *
 * Arguments:	  RingBuffer 	*q
 *
 * return:		  BOOL
 *
 * Description:
 *
 *******************************************************************************/
bool RingBufferIsFull(RingBuffer *q);


/*******************************************************************************
 * Function name: RingBufferWriteEntry
 *
 * Arguments:	  RingBuffer 	*q
 * 				  void 			*entry
 *
 * return:		  BOOL
 *
 * Description:
 *
 *******************************************************************************/
bool RingBufferWriteEntry(RingBuffer *q, void* entry);

/*******************************************************************************
 * Function name: RingBufferReadEntry
 *
 * Arguments:	  RingBuffer 	*q
 * 				  void 			*entry
 *
 * return:		  BOOL
 *
 * Description:
 *
 *******************************************************************************/
bool RingBufferReadEntry(RingBuffer *q, void **entry);

/*******************************************************************************
 * Function name: RingBufferDump
 *
 * Arguments:	  RingBuffer 	*q
 *
 * return:		  void
 *
 * Description:
 *
 *******************************************************************************/
void RingBufferDump(RingBuffer *q);


#endif //_RING_BUFFER_H_
